HealthHeartbeatSeriesSample#

The HealthHeartbeatSeriesSample class provides an interface for accessing heartbeat series samples, representing a series of individual heartbeat intervals recorded over time. These samples are typically used for analyzing heart rhythm and detecting irregularities such as atrial fibrillation.

This class is returned by the public API method Health.queryHeartbeatSeriesSamples().

Use Cases#

• Monitoring heart rhythm during workouts or recovery
• Analyzing irregular heartbeats
• Studying heart behavior during sleep or rest
• Generating datasets for research or diagnostics

Class: HealthHeartbeatSeriesSample#

Properties#

Note: This class currently does not expose individual RR intervals. It represents only the series summary.

Method: Health.queryHeartbeatSeriesSamples(options?)#

Definition#

1function queryHeartbeatSeriesSamples(
2  options?: {
3    startDate?: Date
4    endDate?: Date
5    limit?: number
6    strictStartDate?: boolean
7    strictEndDate?: boolean
8    sortDescriptors?: Array<{
9      key: "startDate" | "endDate" | "count"
10      order?: "forward" | "reverse"
11    }>
12    requestPermissions?: HealthQuantityType[]
13  }
14): Promise<HealthHeartbeatSeriesSample[]>

Parameters#

• startDate (optional): Only return samples on or after this date.
• endDate (optional): Only return samples on or before this date.
• limit (optional): Maximum number of samples to return.
• strictStartDate (optional): If true, only include samples whose startDate equals startDate.
• strictEndDate (optional): If true, only include samples whose endDate equals endDate.
• sortDescriptors (optional): Sort results by startDate, endDate, or count, in forward or reverse order.
• requestPermissions (optional): An array of health quantity types for which to request permissions before querying. You must request permissions for the types you want to query. Default only requests permissions for the heartbeat, heartRateVariabilitySDNN and heartRate types.

Returns#

A Promise resolving to an array of HealthHeartbeatSeriesSample instances, sorted according to the provided descriptors.

Example#

1async function fetchHeartbeatSeries() {
2  const heartbeatSamples = await Health.queryHeartbeatSeriesSamples({
3    startDate: new Date('2024-01-01'),
4    endDate: new Date(),
5    sortDescriptors: [
6      { key: 'startDate', order: 'reverse' }
7    ],
8    limit: 5,
9  })
10
11  for (const sample of heartbeatSamples) {
12    console.log('UUID:', sample.uuid)
13    console.log('Start:', sample.startDate)
14    console.log('End:', sample.endDate)
15    console.log('Beats Count:', sample.count)
16    console.log('Metadata:', sample.metadata)
17  }
18}

Notes#

• If no permission is granted to access heartbeat data, the returned array will be empty.
• Heartbeat series are most commonly recorded by Apple Watch and represent detailed rhythm data over short durations.